Skip to main content

Numerical weather forecasting model ICON-CH1/2-EPS

MeteoSwiss uses two models, ICON-CH1-EPS and ICON-CH2-EPS, to forecast the atmospheric state in Switzerland and its surroundings over a longer period than nowcasting, providing predictions for up to five days. Both models include ensemble data assimilation, where multiple simulations with slightly perturbed initial conditions help account for forecast uncertainty. Forecasts can include the full ensemble or just the unperturbed control run.

Loading map...

The documentation covers the following topics:


Getting started quickly​

Example notebooks: From retrieval to visualization​

These Jupyter notebooks provide examples of how to access and process numerical weather prediction (NWP) model data from MeteoSwiss.

Model specifications​

AttributesICON-CH1-EPSICON-CH2-EPS
Collectionch.meteoschweiz.ogd-forecasting-icon-ch1ch.meteoschweiz.ogd-forecasting-icon-ch2
Horizontal Grid Sizeapprox. 1 kmapprox. 2.1 km
Ensemble Members1121
Forecast Period33 h120 h
GridNative icosahedralNative icosahedral
Temporal Output Resolution1 h1 h
New Model Run (Initialization)every 3 hevery 6 h
Output Data FormatGRIB edition 2GRIB edition 2

Available parameters​

🚧 Temporary Notice Work in Progress​

Users can find information about available parameters, including metadata about height, longitude and latitude, in the collection level assets of the above collections.

Parameter metadata​

A complete set of metadata describing the corresponding parameter is encoded in each record of the GRIB files. Please refer to Decoding GRIB files with ecCodes.

Accessing forecast data​

The data provided in the two collections described in the Model specifications table is accessible for 24 hours. Data older than this is no longer available.

The data is provided in GRIB format, which is a binary format used internationally and defined by WMO.

⚠️ WARNING: Data located at the boundary of the spatial domain may be random.

Forecast data volume​

The following tables summarize the volume of the different forecast files for ICON-CH1-EPS and ICON-CH2-EPS.

ICON-CH1-EPS Data Volume

Single-Level FilesMulti-Level Files
Deterministic199.0 Bytes - 2.2 MiB19.7 - 177.4 MiB
Perturbed1.9 KiB - 22.4 MiB197.1 MiB - 1.7 GiB

ICON-CH2-EPS Data Volume

Single-Level FilesMulti-Level Files
Deterministic175.0 Bytes - 564.7 KiB4.9 MiB - 43.9 MiB
Perturbed3.4 KiB - 11 MiB97.5 MiB - 877.5 MiB

3D grid structure and representation​

The model data is structured on both a horizontal and vertical grid.

Vertical grid​

The vertical grid above the surface is a height-based coordinate system that describes terrain-following model levels. The closer the levels are to the surface, the narrower the layers they define, as shown in the image below. The model levels gradually change into levels of constant height as the distance from the surface increases. Each grid box is delimited at the top and bottom by so-called half levels of the grid, while the full levels are aligned with the center of the grid box.

The vertical grid uses a Lorenz-type staggering, meaning that some parameters are defined at full levels and others, e.g. the vertical velocity W, at half levels. There are 81 discrete half levels and 80 full levels in our data. The levels are numbered from top to bottom.

VerticalLayers
Illustration of ICON's vertical levels, Working with the ICON Model 2024, Figure 3.2


In addition to the vertical grid above the surface (half and full levels), there is also a grid below the land surface to describe parameters such as the soil temperature for example.

In the provided model data, some variables are also defined on a surface (e.g. total precipitation), or at a specific height above ground (e.g. temperature at 2m). To determine the vertical positioning of a parameter and the units corresponding to the vertical surface type, inspect the GRIB2 key typeOfLevel:

  • generalVertical: half levels (-)

  • generalVerticalLayer: full levels (-)

  • depthBelowLandLayer: depth below surface (m)

  • surface: ground or water surface (-)

  • heightAboveGround: specific height above ground (m)

Parameters are classified as either single-level or multi-level:

  • Single-level parameters contain data at a specific vertical level.
  • Multi-level parameters span multiple vertical layers.

For more detailed information on the vertical grid, read section 3.4 in Working with the ICON Model.

Horizontal grid​

The horizontal grid of the ICON-CH1-EPS and ICON-CH2-EPS models is based on a native icosahedral grid used by the ICON model (illustration below).

IcosahedralGrid
Illustration of the ICON grid structure, Working with the ICON Model, Figure 2.1


Since the provided data is defined on the native grid, the horizontal grid points correspond to the center of the circumcircle of each triangle and not to the triangle’s vertices. Therefore, the longitude and latitude information corresponds to the middle of each triangle. For more detailed information on the horizontal grid, read section 2.1 in Working with the ICON Model.

Retrieving forecasts via REST API​

If users prefer not to use the provided Python library to load the data, they can retrieve datasets directly via the REST API by following the step-by-step instructions in this section to obtain forecast data for specific models, parameters, and other customizable variables.

Submitting a POST request​

Filtering and querying forecast data must be done using a POST request. To retrieve a forecast, use a tool like curl and send the request to the API endpoint:

curl -X POST "https://data.geo.admin.ch/api/stac/v1/search" \
     -H "Content-Type: application/json" \
     -d '{
            "collections": [
                "ch.meteoschweiz.ogd-forecasting-icon-ch2"
            ],
            "forecast:reference_datetime": "2025-03-12T12:00:00Z",
            "forecast:variable": "TOT_PREC",
            "forecast:perturbed": false,
            "forecast:horizon": "P0DT00H00M00S"
        }'

Each parameter in the request body serves the following purpose:

  • collections: Defines the forecast model to retrieve (ch.meteoschweiz.ogd-forecasting-icon-ch1 for ICON-CH1-EPS and ch.meteoschweiz.ogd-forecasting-icon-ch2 for ICON-CH2-EPS).
  • forecast:reference_datetime: Specifies the desired forecast initialization time (e.g., 2025-03-12T12:00:00Z).
  • forecast:variable: Indicates the meteorological parameter of interest (TOT_PREC for total precipitation, for example).
  • forecast:perturbed: Boolean flag determining if the request is for deterministic (false) or ensemble (true) data.
  • forecast:horizon: Defines the forecast lead time to retrieve in ISO 8601 duration format (P0DT00H00M00S for data at +0h lead time, i.e. initialization).

Downloading the forecast data​

Upon a successful request, the response will contain a dictionary of metadata, including forecast file links under the assets key. Locate the href field containing the pre-signed URL. Download the GRIB file containing the forecast data using the following command:

wget -O <desired_filename> “<pre-signed URL>”

After downloading your forecast data, it's good practice to verify its integrity before use.

Verifying the data integrity​

To ensure that the downloaded file is not corrupted, compute its SHA-256 hash and verify it against the checksum provided in the file's header field.

Steps:

  1. Open a terminal and generate the SHA-256 checksum of the downloaded file:
sha256sum <downloaded_filename>
  1. Retrieve the checksum from the file’s header field x-amz-meta-sha256 using the following command:
curl -s -i "<pre-signed URL>" | awk -F': ' '/x-amz-meta-sha256/ {print $0}'
  1. Compare the two hash values. If they match, your forecast data file is safe to use.

Once the file is verified, you can proceed with reading the GRIB file, using e.g. the instructions in Decoding GRIB files with ecCodes.

Accessing static grid information: Height, longitude and latitude​

❗ NOTE: Forecast GRIB files do not contain information about height, longitude and latitude. To geolocate or interpret vertical levels, you must use the static vertical and horizontal grid parameter files provided in each collection.
💡 Tip for new users: We recommend inexperienced GRIB file users to take a look at the provided Jupyter Notebooks. The data retrieval with the Python API includes fetching longitude and latitude.

Besides the current forecast files, each collection contains two static files. They store constant information about the height of the half levels (HHL) in the vertical grid and the center point coordinates of each triangle on the horizontal grid.

Accessing horizontal grid parameters​

The static horizontal file stores the longitude and latitude of the center points of each triangle in the horizontal grid. To retrieve this information, follow the steps below:

  1. Submit a GET request specifying the collection you want to download the static horizontal files from (eg. ch.meteoschweiz.ogd-forecasting-icon-ch1 for ICON-CH1-EPS).
curl -X GET https://data.geo.admin.ch/api/stac/v1/collections/ch.meteoschweiz.ogd-forecasting-icon-ch1/assets
  1. Locate the href field under assets in id: horizontal_constants_icon-ch1-eps.grib2 and copy the pre-signed URL.
  2. Download the file with:
wget -O <desired_filename> “<pre-signed URL>”
  1. Once the static GRIB file is downloaded, ensure that the uuidOfHGrid (Universally Unique Identifier for the horizontal grid) key in the data file matches the one in the static horizontal file.

Accessing vertical grid parameters​

In the static vertical file, the heights of the half levels of the vertical grid are provided in meters above mean sea level. In order to associate a value from a data file (for a given parameter) to a height in meters above sea level, follow the steps below:

  1. Submit a GET request specifying the collection you want to retrieve the static vertical files from (e.g., ch.meteoschweiz.ogd-forecasting-icon-ch1 for ICON-CH1-EPS):
curl -X GET https://data.geo.admin.ch/api/stac/v1/collections/ch.meteoschweiz.ogd-forecasting-icon-ch1/assets
  1. Locate the href field under assets in id: vertical_constants_icon-ch1-eps.grib2 and copy the pre-signed URL.
  2. Download the file with:
wget -O <desired_filename> “<pre-signed URL>”
  1. Once the static GRIB file is downloaded, verify that the uuidOfVGrid (Universally Unique Identifier for the vertical grid) key in the data file matches the one in the HHL file.
  2. Retrieve the value for the level key and inspect the typeOfLevel key by listing the GRIB messages:
    • generalVertical: The value of level corresponds to a half level in the HHL file. For each level (i.e., each GRIB message), the variable h provides the height in meters above sea level for every grid point.
    • generalVerticalLayer: The level value corresponds to a full level. To obtain the height in meters above sea level, average the heights of the two surrounding half levels (above and below).
    • Other types of level: These are usually specified directly in meters and are self-explanatory.

Reading forecast files using ecCodes​

Once you have the desired GRIB files, you need a tool to decode the GRIB records. Each GRIB record holds the data for one parameter at one time and at one level. More information about the data format can be found in the Manual on Codes published by WMO. We recommend installing ecCodes from ECMWF to read the data. Follow the installation guide provided by ECMWF here.

Setting the local definitions of the COSMO consortium​

The GRIB format relies on tables and templates to encode the metadata. Those tables allow for example the mapping of a triplet of numbers encoding a parameter to a descriptive string (shortName). The international tables are provided in ecCodes. Additionally, local definitions can be defined by each center. ECMWF specific definitions are also shiped with ecCodes. Some of the provided ICON data also requires the local definitions of the COSMO consortium. In order to provide a consistent and comprehensive set of GRIB tables, check the ecCodes version you installed and clone the corresponding version of the GRIB tables in the same folder:

Then, set GRIB_DEFINITION_PATH for ecCodes to use those tables (add it to your .bashrc to make if availabe in each terminal session):

export GRIB_DEFINITION_PATH=<name_of_your_folder>/eccodes-cosmo-recources/definitions:<name_of_your_folder>r/eccodes/definitions

To check the details of your information, you can run

codes_info

Decoding GRIB files with ecCodes​

This section provides a brief introduction to decoding GRIB files using command-line tools provided by ecCodes. There are also C, Fortran 90 and Python interfaces, please refer to the ecCodes documentation.

Please look up the use of the command-line tools in the ECMWF documentation.

Some useful commands are:

  • List all the GRIB messages in a file:
grib_ls filename.grib
  • Filter GRIB messages based on key-value conditions:
grib_ls -w key1=value1,key2=value2 filename.grib
  • Specify a list of keys to be printed:
grib_ls -p key1,key2 filename.grib
  • Get a detailed view of the content of all GRIB messages:
grib_dump filename.grib
  • Get a detailed view of GRIB messages with filters:
grib_dump -w key1=value1,key2=value2 filename.grib